<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!-- Copyright 1997 The Open Group, All Rights Reserved -->
<title>pthread_rwlock_rdlock</title>
</head><body bgcolor=white>
<center>
<font size=2>
The Single UNIX &reg; Specification, Version 2<br>
Copyright &copy; 1997 The Open Group

</font></center><hr size=2 noshade>
<h4><a name = "tag_000_007_1603">&nbsp;</a>NAME</h4><blockquote>
pthread_rwlock_rdlock, pthread_rwlock_tryrdlock
- lock a read-write lock object for reading
</blockquote><h4><a name = "tag_000_007_1604">&nbsp;</a>SYNOPSIS</h4><blockquote>
<pre><code>

#include &lt;<a href="pthread.h.html">pthread.h</a>&gt;

int pthread_rwlock_rdlock(pthread_rwlock_t <i>*rwlock</i>);
int pthread_rwlock_tryrdlock(pthread_rwlock_t <i>*rwlock</i>);
</code>
</pre>
</blockquote><h4><a name = "tag_000_007_1605">&nbsp;</a>DESCRIPTION</h4><blockquote>
The 
<i>pthread_rwlock_rdlock()</i>
function applies a read lock to the read-write lock referenced by
<i>rwlock</i>. 
The calling thread acquires the read lock if a writer does not
hold the lock and there are no writers blocked
on the lock.  It is unspecified whether the calling thread
acquires the lock when a writer does not hold the lock
and there are writers waiting for the lock.  If a writer holds
the lock, the calling thread will not acquire the
read lock.  If the read lock is not acquired, the calling
thread blocks (that is, it does not return from the
<i>pthread_rwlock_rdlock()</i>
call) until it can acquire the lock.
Results are undefined if the calling thread holds
a write lock on <i>rwlock</i>
at the time the call is made.
<p>
Implementations are allowed to favour writers over readers
to avoid writer starvation.
<p>
A thread may hold multiple concurrent read locks on <i>rwlock</i>
(that is, successfully call the
<i>pthread_rwlock_rdlock()</i>
function <i>n</i> times). If so, the thread
must perform matching unlocks (that is, it must
call the 
<i><a href="pthread_rwlock_unlock.html">pthread_rwlock_unlock()</a></i>
function <i>n</i> times).
<p>
The function 
<i>pthread_rwlock_tryrdlock()</i>
applies a read lock
as in the 
<i>pthread_rwlock_rdlock()</i>
function
with the exception that the function fails if any thread holds a
write lock on <i>rwlock</i> or there are writers blocked
on <i>rwlock</i>.
<p>
Results are undefined if any of these functions are called with
an uninitialised read-write lock.
<p>
If a signal is delivered to a thread waiting for a read-write
lock for reading, upon return from the signal handler
the thread resumes waiting for the read-write lock for
reading as if it was not interrupted.
</blockquote><h4><a name = "tag_000_007_1606">&nbsp;</a>RETURN VALUE</h4><blockquote>
If successful, the 
<i>pthread_rwlock_rdlock()</i>
function returns zero. 
Otherwise, an error number is returned
to indicate the error.
<p>
The function 
<i>pthread_rwlock_tryrdlock()</i>
returns zero if the
lock for reading on the read-write lock object
referenced by <i>rwlock</i> is acquired. 
Otherwise an error number 
is returned to indicate the error.
</blockquote><h4><a name = "tag_000_007_1607">&nbsp;</a>ERRORS</h4><blockquote>
The
<i>pthread_rwlock_tryrdlock()</i>
function will fail if:
<dl compact>

<dt>[EBUSY]<dd>
The read-write lock could not be acquired for reading because a
writer holds the
lock or was blocked on it.

</dl>
<p>
The
<i>pthread_rwlock_rdlock()</i>
and
<i>pthread_rwlock_tryrdlock()</i>
functions may fail if:
<dl compact>

<dt>[EINVAL]<dd>
The value specified by <i>rwlock</i> does not refer to an initialised
read-write lock object.

<dt>[EDEADLK]<dd>
The current thread already owns the read-write lock for writing.

<dt>[EAGAIN]<dd>
The read lock could not be acquired because the maximum number of 
read locks
for <i>rwlock</i> has been exceeded.

</dl>
</blockquote><h4><a name = "tag_000_007_1608">&nbsp;</a>EXAMPLES</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_007_1609">&nbsp;</a>APPLICATION USAGE</h4><blockquote>
Similar functions are being developed by IEEE PASC.
In keeping with its objective of ensuring that CAE
Specifications are fully aligned with formal standards, The Open Group
intends to add any new interfaces adopted by an official IEEE standard
in this area.
<p>
Realtime applications may encounter priority inversion when using
read-write locks.
The problem occurs when a high priority thread &quot;locks&quot; a read-write
lock that is about to be &quot;unlocked&quot; by a low priority thread, but
the low priority thread is preempted by a medium priority thread.
This scenario leads to priority inversion; a high priority thread is
blocked by lower priority threads for an unlimited period of time.
During system design, realtime programmers must take into account the
possibility of this kind of priority inversion.
They can deal with it in a number of ways, such as by having critical
sections that are guarded by read-write locks execute at a high
priority, so that a thread cannot be preempted while executing in its
critical section.
</blockquote><h4><a name = "tag_000_007_1610">&nbsp;</a>FUTURE DIRECTIONS</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_007_1611">&nbsp;</a>SEE ALSO</h4><blockquote>
<i><a href="pthread.h.html">&lt;pthread.h&gt;</a></i>,
<i><a href="pthread_rwlock_init.html">pthread_rwlock_init()</a></i>,
<i><a href="pthread_rwlock_wrlock.html">pthread_rwlock_wrlock()</a></i>,
<i><a href="pthread_rwlockattr_init.html">pthread_rwlockattr_init()</a></i>,
<i><a href="pthread_rwlock_unlock.html">pthread_rwlock_unlock()</a></i>.
</blockquote><hr size=2 noshade>
<center><font size=2>
UNIX &reg; is a registered Trademark of The Open Group.<br>
Copyright &copy; 1997 The Open Group
<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]

</font></center><hr size=2 noshade>
</body></html>
